The Correct Way to Reference Dynamic Link Libraries (DLLs) in .NET Projects

How to use DLL files written by others

Generally, it is not recommended to directly reference DLL files written by others because C# has a NuGet Server. Most free packages today can be found there. If it is an internal company library, you can also ask a technical consultant to set up a NuGet Server accessible only within the intranet, and have people package the written library into a NuGet file and upload it. Those who need to reference it can simply add this NuGet Server link in their Visual Studio to use it. As for why you should use NuGet to download packages instead of directly referencing DLL files:

• NuGet makes upgrading and downgrading versions convenient.
• DLL files have Framework compatibility issues. Many packages on NuGet now support multiple Framework versions. When you download from NuGet, it will find the most suitable version to install based on your project's Framework. However, this also means that when the project's Framework version changes, you need to run commands in the Package Manager to reinstall the referenced packages and manually modify the restored configuration files.
• Packages have dependency issues. When installing, NuGet will automatically install other packages that the target package depends on.

Explaining the correct way to reference DLL files using the NuGet approach

When installing a package from NuGet, a "packages" folder is created under the solution, which stores the DLL files of the installed packages. Opening the project file (.csproj) will reveal that the sources of the referenced DLLs are all stored under "packages".

Therefore, the correct way to reference is as follows:

1. Create a folder under the solution (or higher up if the solution is not at the root of the version control). It is recommended not to name it "packages" to avoid confusion.
2. Place the DLL files to be referenced in this folder. When adding references in each project, always reference the DLL files from this folder.
3. This folder must be included in version control. "packages" does not need to be in version control because NuGet can be configured to restore the DLLs under "packages" from the NuGet Server.

Precautions for directly referencing DLL files written by others

• Common mistakes made by beginners:

  1. The "bin" folder of a project is the output directory after compilation and is normally not included in version control. If you reference DLL files correctly, when the DLL file is missing from "bin", the project can copy the DLL file from the source to "bin" during compilation. However, when you place the DLL file in "bin" to reference it, the project file (.csproj) records the source of the DLL file as being in "bin". When you delete the DLL file in "bin" and rebuild, it will fail to copy to "bin" because the source DLL file no longer exists.

  

  1. It is impossible to manage the versions of referenced DLLs across multiple projects in the same solution, because many people do not pay attention to which extra DLL files other projects are referencing. Every time a DLL is referenced, it is placed in "bin" rather than a common source, making it very likely that different projects will reference different versions.

• Website Projects (WSP) do not have project files. Where is the location of the DLL file reference recorded?

  When adding a reference in a WSP, in addition to generating the DLL file in the "bin" folder, a file named "{DLL name}.dll.refresh" is created. Opening this file reveals the recorded source of the DLL file reference.

  

  

  Although theoretically "bin" is not included in version control, the ".dll.refresh" files inside it must be included in version control.

Change Log

• 2022-09-30 Initial document creation.